<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Luminance HDR User Manual - Contributing - Translating</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<link href="style.css" rel="stylesheet" type="text/css" />
</head>
<body>
<h2>Translating</h2>

<h3>Translating desktop entry</h3>

<p>On Linux systems .desktop files are used to build system menus that list applications available to users. Here is what it looks like in GNOME desktop environment:</p>

<p><img src="images/not-translated-menu-item.png" /></p>

<p>Luminance HDR ships with such a file as well. It is located in root directory with source code and gets installed to /usr/share/applications or /usr/local/share/applications, depending on your preferences.</p>

<p>To get a localized menu entry you need to do a very simple thing:</p>

<ol>
<li>Open this file in your preferred text editor and make sure you opened it as a UTF-8 encoded text file.</li>
<li>Create a new entry which looks like "Comment[LANG]=Create and tonemap HDR images", where LANG is a two-letter code for your language (as referenced by <a href="http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes">ISO-639-1</a>) and everything after "=" is translated.</li>
<li>Create a new entry which looks like "GenericName[LANG]=HDR imaging".</li>
<li>Save.</li>
<li>Test by running 'sudo make install' (if Luminance HDR is already installed or just 'sudo cp luminance.desktop /usr/share/applications/' and look in the menu.</li>
</ol>

<p>You should see something like this:</p>

<p><img src="images/translated-menu-item.png" /></p>

<p><a href="https://sourceforge.net/tracker/?group_id=183831&atid=906822">Send</a> the updated file to us.</p>

<h3>Translating user interface</h3>

<p>The very first thing you need to translate Luminance HDR into your native language is to get source code from the current development branch. To do this, you need a Subversion client (<span class="code">svn</span> being the regular command line client). Then type</p>

<p><tt>svn co https://qtpfsgui.svn.sourceforge.net/svnroot/qtpfsgui/trunk/qtpfsgui qtpfsgui</tt></p>

<p>somewhere in your home directory to fetch source code, so that you always have access to it.</p>

<p>Then you will need to install Qt development package that contains Linguist&nbsp;&mdash; the application to assist you with translating. On Linux start your package manager and look for a package named something like qt4-dev, install it.</p>

<p>The next steps are as follows:</p>

<ol>
	<li>Go to the top level directory of Luminance HDR's source code.</li>
	<li>Open the file called <em>project.pro</em>.</li>
	<li>Find a section that starts with "TRANSLATIONS =" and add a new line that looks like "i18n/lang_LOCALE.ts \", where LOCALE is a two-letter code for your language (as referenced by <a href="http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes">ISO-639-1</a>), lowercase, e.g. <em>pt</em> for Portuguese.</li>
	<li>Save the <em>project.pro</em> file.</li>
	<li>Open console in that directory and run "$ lupdate-qt4 project.pro" command. This will create a new translation file (and update existing translation files).</li>
	<li>Open your lang_LOCALE.ts file in Linguist and start translating.</li>
	<li>To test your translation, use <em>File&nbsp;&gt; Release</em> menu item in Linguist to create a binary version of translation and then run <span class="code">sudo make install</span> from console to quickly install created translation in the right place.</li>
	<li>When your work is done, compress this lang_LOCALE.ts file to a ZIP, GZ or BZ2 archive and submit it via <a href="https://sourceforge.net/tracker/?group_id=183831&atid=906822">patches tracker</a>.</li>
</ol>

<p>Here are some tips to help you make translation better.</p>

<p>Translating Luminance HDR takes a while, so it's best to translate those parts of user interface that you use most of the time. This will give you a false, but useful feeling of accomplishment and motivation to finish the whole work.</p>

<p>Test your translation as frequently as possible. This is especially important for dialogs that you rarely use.</p>

<p>Make sure you find a good balance between short and easy to understand phrases and words. English language is known to have relatively shorter words, so in most cases your translation will make user interface a bit larger. But if you start using abbreviations or shorter synonyms that don't quite fit the context, users won't appreciate that either.</p>

<p>Some translatable messages use variables like <em>%1</em>. Those are substituted by some values. For example, in "Using %1 thread(s)" (Batch Tonemapping dialog) this variable is substituted with amount of threads used to process HDR images into LDR images. When you type these variables manually, you can make a mistake and the trick with a variable won't work. So it's better to paste original text to translation entry field by pressing <b>Ctrl</b>+<b>B</b> in Linguist and then replace this original text with translation, leaving all present variables intact.</p>

<h3>Translating documentation</h3>

<p>The documentation is inside <em>help</em> directory and consists of menu.xml file that defines table of contents, HTML files with text and illustrations in PNG or JPEG files.</p>

<p>Every translation is kept in its own directory named with two-letter language code like <em>ru</em> for Russian or <em>es</em> for Spanish. So download source code, unpack it and create a copy of <em>help/en</em> directory in <em>help</em> directory.</p>

<p>Start translating. It's best to translate table of contents first and proceed with actual content later. To translate table of contents open menu.xml file in your editor of choice and translate values of every <em>text</em> attribute. E.g. for &lt;area text="Setting up Luminance HDR" file="prefs.html"&gt; translatable text will be "Setting up Luminance HDR".</p>

<p>To test your translation open a terminal window, go to the top level directory with source code, and run <tt>sudo make install</tt> to reinstall Luminance HDR. All available translations will be automatically copied to the right place, and you will have to restart Luminance HDR to let it pick the added translation. However, as you progress with your translation, you only need to restart help browser to see changes in table of contents and you don't even need to restart the help browser to see changes in separate chapters&nbsp;&mdash; just click on some other chapter and go back again.</p>

<p>If user interface is not localized, you might want to do it before translating docs. Some users might complain and tell you that user interface in English is a de-facto standard and thus localized documentation should refer only to English UI. But this is just because they have grown up to use unlocalized software, so don't you worry.</p>

<p>The English (and Russian) translations have screenshots with <em>Dust</em> theme for both GTK+ and Metacity (and GTK+ engine for Qt), and Droid Sans 9pt font. You don't have to try to reproduce that, but please be visually consistent across your translation.</p>

<p>Please keep all of your illustrations below 800 pixels on the longer side. The reason is: when an image doesn't fit help browser's window, a nasty horizontal scrollbar appears. To get rid of it you need to grow width of the window, and that means that text will reflow and there will be too long barely readable lines of text.</p>

<p>When you are done, archive help/LANGUAGE directory with your translation and <a href="https://sourceforge.net/tracker/?group_id=183831&atid=906822">send it</a> to us.</p>

</body>
</html>
